{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Overview Of The BPTK-Py Tutorial\n",
    "\n",
    "This tutorial contain sample agent-based and System Dynamics models along with Jupyter notebooks that illustrate the features of the BPTK-Py framework. This tutorial is designed as a companion to the [BPTK-Py online documentation](http://bptk.transentis.com).\n",
    "\n",
    "## Installation\n",
    "\n",
    "### Using Docker\n",
    "\n",
    "If you have Docker installed (e.g. Docker Desktop on MacOS or on Windows), follow these steps:\n",
    "\n",
    "1. On the command line, move into a directory where you would like to store the BPTK-Py tutorial. \n",
    "2. Clone this repository: ```git clone https://github.com/transentis/bptk_py_tutorial.git```\n",
    "3. Run ```docker-compose up```\n",
    "4. Point your browser at [http://localhost:8888](http://localhost:8888) – this will open JupyterLab showing the contents of your directory. \n",
    "5. Open the notebook ```readme.ipynb``` from within JupyterLab.\n",
    "6. When you are finished, close your browser and call ```docker-compose down``` from within your directory. This will stop and remove the container.\n",
    "\n",
    "### Using a virtual environment\n",
    "\n",
    "First, make sure you have Python 3 installed on your machine.\n",
    "\n",
    "Then follow these steps:\n",
    "\n",
    "1. On the command line, move into a directory where you would like to store the BPTK-Py tutorial. \n",
    "2. Clone this repository: ```git clone https://github.com/transentis/bptk_py_tutorial.git```\n",
    "3. Install a virtual environment in that directory: ```python3 -m venv venv```\n",
    "4. Activate the virtual environment: ```source venv/bin/activate``` (MacOS/Linux) or `venv\\scripts\\activate.bat` (Windows)\n",
    "5. Install the necessary python modules: ```pip install -r requirements.txt```\n",
    "6. Start JupyerLab: ```jupyter lab```\n",
    "7. Your browser will open showing JupyterLab and your chosen directory\n",
    "8. Open the notebook ```readme.ipynb``` from within JupyterLab\n",
    "\n",
    "## Getting Started\n",
    "\n",
    "This tutorial contains a number of Jupyter notebooks that illustrate usage of the BPTK-Py framework. Which one to get started with depends on whether you are interested in Agent-based modeling, in System Dynamics using XMILE (e.g. using Stella Architect or iThink) or in our domain-specific language for System Dynamics (SD DSL):\n",
    "\n",
    "* _Agent-based Modeling_ – start with [Agent-based Modeling with BPTK-Py](abm/in-depth/in_depth_agent_based_modeling/in_depth_agent_based_modeling.ipynb)\n",
    "* _SD with XMILE_ – start with [Working With XMILE System Dynamics Models](xmile/how-to/how_to_working_with_xmile/how_to_working_with_XMILE.ipynb)\n",
    "* _SD DSL_ – start with [A Simple Python Library for System Dynamics](sd-dsl/in-depth/in_depth_simple_python_library_sd_dsl/in_depth_simple_python_library_sd_dsl.ipynb)\n",
    "\n",
    "## Contents\n",
    "\n",
    "* __Step by Step Guides__\n",
    "    * [Introduction to System Dynamics with Python](step-by-step-guides/introduction_sd_dsl/introduction_sd_dsl.ipynb). Introduction to System Dynamics using the SD DSL, for those new to dynamic modeling.\n",
    "* __General Information on The Framework__\n",
    "    * In Depth Discussions\n",
    "        * [The Architecture of the BPTK-Py Framework](general/in-depth/in_depth_bptk_py_architecture/in_depth_bptk_py_architecture.ipynb) Explains the overall architecture of the BPTK-Py framework.\n",
    "        * [Scenarios In Depth](general/in-depth/in_depth_scenarios/in_depth_scenarios.ipynb) Explains the scenario definition format and how to add and manipulate scenarios at run-time.\n",
    "    * HOW TOs\n",
    "        * [How To: Accessing Raw Simulation Results](general/how-to/how_to_accessing_raw_simulation_results/how_to_accessing_raw_simulation_results.ipynb) Explains how to access raw simulation results with scenarios.\n",
    "        * [How To: Advanced Plotting Features](general/how-to/how_to_advanced_plotting_features/how_to_advanced_plotting_features.ipynb) Discusses some advanced features of the `bptk.plot_scenarios` method.\n",
    "        * [How To: Building Interactive Dashboards](general/how-to/how_to_interactive_dashboards/how_to_interactive_dashboards.ipynb). Shows how do build simple interactive dashboards using the `bptk.dashboard` method.\n",
    "        * [How To: Developing Advanced User-Interfaces](general/how-to/how_to_developing_advanced_user_interfaces/how_to_developing_advanced_user_interfaces.ipynb) Explains how to develop more advanced user interfaces using Jupyter Widgets, Pandas dataframes and Matplotlib.\n",
    "* __Agent-based Modeling__\n",
    "    * In Depth Discussions\n",
    "        * [Agent-based Modeling with BPTK-Py](abm/in-depth/in_depth_agent_based_modeling/in_depth_agent_based_modeling.ipynb) Illustrates how to create an agent-based implementation of a simple project management model.\n",
    "* __System Dynamics using XMILE__\n",
    "    * In Depth Discussions\n",
    "        * [Writing Computational Essays Using Simulation Models](xmile/in-depth/writing_computational_essays/writing_computational_essays.ipynb). Introduction to writing Computational Essays around System Dynamics models created using the XMILE Standard (e.g. using  ®Stella or ®iThink).\n",
    "    * HOW TOs\n",
    "        * [How To: Working With XMILE System Dynamics Models](xmile/how-to/how_to_working_with_xmile/how_to_working_with_XMILE.ipynb) Illustrates the quickest route to importing a System Dynamics model stored in the XMILE format, such as those created with ®Stella (*.stmx) or ®iThink (*.itmx).\n",
    "        * [How To: Exporting Simulation Results](xmile/how-to/how_to_exporting_simulation_results/how_to_exporting_simulation_results.ipynb) Explains how to export simulation results into a spreadsheet.\n",
    "        * [How To: Working with Arrayed Variables in XMILE Models](xmile/how-to/how_to_xmile_arrays/how_to_XMILE_arrays.ipynb) Explains how to use arrayed operators aund functions in BPTK_Py\n",
    "        \n",
    "* __System Dynamics using SD DSL__\n",
    "    * In Depth Discussions\n",
    "        * [A Simple Python Library for System Dynamics](sd-dsl/in-depth/in_depth_simple_python_library_sd_dsl/in_depth_simple_python_library_sd_dsl.ipynb). Introduction to building System Dynamics models directly in Juptyer Notebooks, using SD DSL, a specially created domain specific language for System Dynamics, that is part of BPTK-Py.\n",
    "        * [SD DSL Functions](sd-dsl/in-depth/in_depth_sd_dsl_functions/in_depth_sd_dsl_functions.ipynb) An overview of how to use the SD DSL operators such as MIN, MAX and DELAY.\n",
    "    * HOW TOs\n",
    "        * [How To: Creating User Defined Functions in SD Models](sd-dsl/how-to/how_to_sd_user_defined_functions/how_to_sd_user_defined_functions.ipynb) Explains how to create user defined functions in SD models.\n",
    "\n",
    "  \n",
    "    \n",
    "## Learning More About System Dynamics and Agent-based Modeling\n",
    "\n",
    "The main objective of this tutorial is to show you how to use the BPTK-Py framework and not to explain System Dynamics or Agent-based modeling. \n",
    "\n",
    "For those new to dynamic modeling, we have included a small step-by-step [Introduction to System Dynamics with Python](step-by-step-guides/introduction_sd_dsl/introduction_sd_dsl.ipynb).\n",
    "\n",
    "You can also find further introductions on our blog:\n",
    "\n",
    "* [Step-by-step introduction to System Dynamics](https://www.transentis.com/step-by-step-tutorials/introduction-to-system-dynamics/) using the simple project management model.\n",
    "* Introduction to the [Bass Diffusion Model](https://www.transentis.com/causal-loop-diagramming/).\n",
    "* The [Customer Acquisition Model](https://www.transentis.com/an-example-to-illustrate-the-business-prototyping-methodology) is discussed in our series of post introducing the Business Prototyping Methodology.\n",
    "\n",
    "## Advanced Examples on GitHub\n",
    "\n",
    "You can find more advanced examples of models and dashboards build using BPTK on GitHub:\n",
    "\n",
    "* [COVID Simulation](https://github.com/transentis/sim-covid-19). Jupyter notebooks and dashboards illustrating the SIR model.\n",
    "* [COVID Simulation Dashboard](https://github.com/transentis/sim-covid-dashboard). A web-based simulation dashboard for the COVID simulation built using our BPTK Widgets library for Javascript. View a [live version](http://www.covid-sim.com) of the dashboard online.\n",
    "* [Beer Distribution Game](https://github.com/transentis/beergame). In-depth analysis of the beergame using both System Dynamics and Agent-based simulation. Includes an illustration of how to use BPTK in conjunction with reinforcement learning to train agents to play the beergame autonomously. \n",
    "\n",
    "## Get in Touch\n",
    "\n",
    "Please let us know if you need help getting started, if you find a bug or are missing important functionality.\n",
    "\n",
    "We are keen to hear how you use BPTK-Py – your feedback is invaluable in helping us improve BPTK-Py.\n",
    "\n",
    "You can best reach us per e-mail at [support@transentis.com](mailto:support@transentis.com)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}